REST (REpresentational State Transfer) is an “architectural style” described by Roy Fielding in his PhD dissertation Fielding2000. REST seeks to adapt the architecture of the Web, along with its scalability, performance, and other advantages, as a platform for any kind of application. In REST, as on the Web, a resource is an item of interest. Each resource has an address (URI) and one or more representations (a file with a given media type). A client can interact with a resource through a URL and these interactions in turn act as the engine of application state because the representations provide hypermedia links offering alternative directions the client can take to proceed through the workflow. The RESTful ideal is that just as you interact with a Web site and choose which step to take next, without being frustrated that the layout of the page and links offered have changed since the last time you visited the site, so a client using a RESTful API can pick its way through a workflow without demanding a fixed, brittle contract. Likewise, the Web's mature and well-understood caching mechanisms can improve the performance and scalability of your application, protecting the server from spikes in traffic and the client from brief interruptions in the server's availability.
While many APIs describe themselves as RESTful, some RESTful APIs are more RESTful than others. At the most rudimentary level, APIs may employ one or more URIs, but still use only one method (GET, POST) to tunnel their requests over HTTP and do not represent a radical break from WS-* services. APIs that embrace the RESTful architecture more fully offer a larger number of resources, each with a URI, and map a variety of HTTP verbs to the Create Read Update Delete (CRUD) operations found in most applications. In these services, parameters are passed in with requests either as elements of the URI or as query parameters appended to the URI. The Web's caching infrastructure also comes into play. Finally, in an ideal more often discussed than achieved, services that fully embrace the idea of hypermedia as the engine of application state (HATEOS), relying on the client to navigate through the workflow in the same way an end-user at an e-commerce site would, by inspecting the available links and picking the appropriate one.
As a REST service is being developed, the goal is to ensure that the documentation accurately matches the implementation. Once a REST service reaches a mature state, or is released publicly, the documentation becomes a contract; both clients and alternate implementations use this contract to guide their development. Interoperability between all parties requires that both the documentation and the implementation remain stable, even in the face of bug fixes, upgrades, enhancements, and the introduction of new features via extensions.
In the presence of these changes, there always exists the possibility that either REST service implementation or documents may inadvertently drift from one another. This drift often introduces incompatibilities that can cause clients to fail. Thus, it is important to constantly test that the implementation and documentation of a REST service conform to one another. Unfortunately, document conformance is typically not focused on, nor the intricate details of the REST/HTTP aspects of the service. Instead, testing typically focuses on the functionality of a REST service itself which can result in a number of incompatibilities. Because a focus on functional testing has little to no regard to documentation of the service, cases may arise where both the implementation and testing of a REST service drift away from the documents simultaneously. Adding to the complexity is the fact that service developers tend to allow their implementations to be flexible and loose when accepting messages from clients—this means that conformance and functional tests may inadvertently drift from the service contract without notice.
Accordingly, it is desirable to validate documentation of a REST service during development.